Document GtkSizeGroup::ignore-hidden as broken

...and deprecate it, recommending GtkStack as an alternative.

diff --git a/gtk/gtksizegroup.c b/gtk/gtksizegroup.c
index 5d3eaf1a3b3ea740354aa21a5bc4b926aa877fb8..cf7c152dddbb7015fd0bacaabea085e2ed1078f2 100644 (file)
--- a/gtk/gtksizegroup.c
+++ b/gtk/gtksizegroup.c
@@ -235,10 +235,17 @@ gtk_size_group_class_init (GtkSizeGroupClass *klass)
   /**
    * GtkSizeGroup:ignore-hidden:
    *
-   * If %TRUE, unmapped widgets are ignored when determining 
+   * If %TRUE, unmapped widgets are ignored when determining
    * the size of the group.
    *
    * Since: 2.8
+   *
+   * Deprecated: 3.22: Measuring the size of hidden widgets has not worked
+   *     reliably for a long time. In most cases, they will report a size
+   *     of 0 nowadays, and thus, their size will not affect the other
+   *     size group members. In effect, size groups will always operate
+   *     as if this property was %TRUE. Use a #GtkStack instead to hide
+   *     widgets while still having their size taken into account.
    */
   g_object_class_install_property (gobject_class,
                                    PROP_IGNORE_HIDDEN,
@@ -247,7 +254,7 @@ gtk_size_group_class_init (GtkSizeGroupClass *klass)
                                                          P_("If TRUE, unmapped widgets are ignored "
                                                             "when determining the size of the group"),
                                                          FALSE,
-                                                         GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY));
+                                                         GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY|G_PARAM_DEPRECATED));
 }
 
 static void
@@ -389,11 +396,18 @@ gtk_size_group_get_mode (GtkSizeGroup *size_group)
  * @size_group: a #GtkSizeGroup
  * @ignore_hidden: whether unmapped widgets should be ignored
  *   when calculating the size
- * 
+ *
  * Sets whether unmapped widgets should be ignored when
  * calculating the size.
  *
- * Since: 2.8 
+ * Since: 2.8
+ *
+ * Deprecated: 3.22: Measuring the size of hidden widgets has not worked
+ *     reliably for a long time. In most cases, they will report a size
+ *     of 0 nowadays, and thus, their size will not affect the other
+ *     size group members. In effect, size groups will always operate
+ *     as if this property was %TRUE. Use a #GtkStack instead to hide
+ *     widgets while still having their size taken into account.
  */
 void
 gtk_size_group_set_ignore_hidden (GtkSizeGroup *size_group,
@@ -424,6 +438,13 @@ gtk_size_group_set_ignore_hidden (GtkSizeGroup *size_group,
  * Returns: %TRUE if invisible widgets are ignored.
  *
  * Since: 2.8
+ *
+ * Deprecated: 3.22: Measuring the size of hidden widgets has not worked
+ *     reliably for a long time. In most cases, they will report a size
+ *     of 0 nowadays, and thus, their size will not affect the other
+ *     size group members. In effect, size groups will always operate
+ *     as if this property was %TRUE. Use a #GtkStack instead to hide
+ *     widgets while still having their size taken into account.
  */
 gboolean
 gtk_size_group_get_ignore_hidden (GtkSizeGroup *size_group)

diff --git a/gtk/gtksizegroup.h b/gtk/gtksizegroup.h
index ae03cf68a275d3c178f710df68558b5ff49460a1..0f09df547de7724d57e57d5e3d50559bd9f999d5 100644 (file)
--- a/gtk/gtksizegroup.h
+++ b/gtk/gtksizegroup.h
@@ -68,10 +68,10 @@ void             gtk_size_group_set_mode      (GtkSizeGroup     *size_group,
                                               GtkSizeGroupMode  mode);
 GDK_AVAILABLE_IN_ALL
 GtkSizeGroupMode gtk_size_group_get_mode      (GtkSizeGroup     *size_group);
-GDK_AVAILABLE_IN_ALL
+GDK_DEPRECATED_IN_3_22
 void             gtk_size_group_set_ignore_hidden (GtkSizeGroup *size_group,
                                                   gboolean      ignore_hidden);
-GDK_AVAILABLE_IN_ALL
+GDK_DEPRECATED_IN_3_22
 gboolean         gtk_size_group_get_ignore_hidden (GtkSizeGroup *size_group);
 GDK_AVAILABLE_IN_ALL
 void             gtk_size_group_add_widget    (GtkSizeGroup     *size_group,